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1 Overview 


1 


ECO introduces two new components for use in ASP.NET applications. These components work with the new ASP.NET 
DataSourceControl approach for creating websites. Although it is possible to use standard ECO handles in ASP.NET 
applications it is recommended that these new components (EcoDataSource, EcoSpaceManager) are used instead, and 
therefore these are the only components that will be covered in this tutorial. 


1 
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2 Prerequisites and goais 


Prerequisites 

To successfuiiy foiiow this document the user shouid have read the preceding articies in this series and have a copy of the 
modei created. 
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Goals 

By the end of this document you wili be abie to 

• Create ECO ASP.NET appiications. 

• Use instances of ECO modeied ciasses with standard ASP.NET controis such as DataGridView. 

• Create a master/detaii web Ui. 

• Bind drop down iists of objects to the property of a singie object. 

• Vaiidate objects. 

• Pass objects references across page requests. 

• Manage EcoSpace iife time and pooiing options. 

• Work with muitipie EcoSpace instances and session settings. 


2 
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3 Before you start... 


The persistenceMapperXmil .FiieName property on PersistenceMapperProvider is set to "data.xmi". As this is a reiative path 
the fiie wiil be created reiative to the project that creates the PersistenceMapperProvider, so effectiveiy the expected location 
of the fiie wiii change depending on whether you run the WinForm appiication or Web appiication. 


Ordinariiy you would use a proper data storage in a situation like this, but to avoid having to choose a specific RDBMS for 
these QuickStart articles the XML persistence wiii continue to be used. In order to achieve this a smaii change must be 
made to the PersistenceMapperProvider component so that the data.xmi fiie is aiways iocated in a predictabie iocation. 


View the source for the PersistenceMapperProvider and change the source as foilows: 


public QuickStartPMP ( ) : based 
{ 

InitializeComponent () ; 

//Use a predictable file path 
SetXmlFileName ( ) ; 


private void SetXmlFileName ( ) 

{ 

string xmlFileName = 

Environment . GetFolderPath (Environment . SpecialFolder . LocalApplicationData) ; 

xmlFileName = System . 10 . Path . Combine (xmlFileName, "CapableOb jectsWECO Quick 
StartWSharedData" ) ; 

System . 10 . Directory . Great eDirectory (xmlFileName) ; 
xmlFileName = System . 10 . Path . Combine (xmlFileName, "data.xmi"); 
persistenceMapperXmil . FiieName = xmlFileName; 


If you have chosen to use an RDBMS as your data storage there is no need to perform these steps. 
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4 Web auto forms 


If you look in your QuickStart.ASP project you wiii see a web form named "AutoForm". Web auto forms are the ASP 
equivaient of the prototype tooi in EcoModeier; they aliow you to quickly test your model in a web environment by browsing 
classes in the model, creating, updating, deleting instances, and linking / unlinking objects via their associations. 


Ensure the ASP project is the default by right-clicking it and selecting "Set As SetUp Project", then ensure the AutoForm is 
the default page by right-clicking it and selecting "Set As Start Page". Now run the project. 


3 Eco ASP AutoForm • Microsoft Internet Explon 


File Edit View Favorites Tools Help 
Qeack - 0 iZl Search 

Address http://localhost; 1235/AutoForm.aspx 

|All classes 

ECOModelRoot 
Article 
ArticleType 
Author 


Show 

Show Create 
Show Create 
Show Create 


1 . On the auto form you will see a list of classes in the model. To start click "Show" hyperlink next to ArticleType. You will 
now be presented with a form like so: 


3 Eco ASP AutoForm • Microsoft Internet Explon 


File Edit View Favorites Tools Help 


o Back -0 L3 [?1 ^ Search 

Address http://lQcalhQst;1235/AutoForm.aspx?Class=Art 


ArticleType All classes 

Filter 

Results 


^ ^ Page 1;0- Objects 1-0 

Detail I D Namel 


f Createl 


Note: If you performed the steps in QuickStart 6 (Making the EcoSpace persistent) you will see data. If not you will see no 
data because the path to the data file in persistenceMapperXmlI.FileName is relative to the running application. If you intend 
to use the same XML file for both WinForm and Web app projects you will need to change this path. Obviously it is not 
recommended that you use XML for a released application. 


2. Click the "Create" hyperlink to create a new instance of ArticleType. 
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ArticleTvpe 

Attributes 

ID 

Name 


|winForm[~ 


Submit Changes ]| Delete Instance 


3. Enter "WinForm" as the name of the ArticieType and ciick the "Submit Changes" button to save. 

4. Now ciick the "ArticieType" hyperiink at the top ieft of the form to return to the iist of ArticieType instances. 

5. Ciick "Create" again and create another articie type named "ASP .NET" and save it. Note how you cannot change the ID, 
this text box has been made read oniy because it is auto-assigned by the database. 

6. Now ciick the "Aii ciasses" hyperiink at the top right of the form. Create two new Author instances. 



^ ^ Page 1/1 - Objects 1-2 

Detail EmailAddress FirstName I D LastName Password Salutation FullName AutoPublishArticles 

Detail me@home.com John 1 Smith secret Mr Mr John Smith True 

Detail him@home.com Fred 3 Smith secret Mr Mr Fred Smith False 

f Createl 

7. Now click the "Detail" hyperlink for the first author to view the author's details. 

8. At the bottom of the form is a list of roles (association ends.) In this list you will see "Articles", click the "Add New Article" 
link. 


Article 

Article All classes 

Attributes 

- 

Body 

is the body ofmyarticle| 

Description 

This is the description | 

ID 

1 I 

Title 

My first article | 

Summary 

by Mr John Smith | 

ReasonRejected 

<NULL> I 

ReviewState 

I 

MainState 

Authoring | 


Submit Changes || Delete Instance | 

Roles 

- 

ArticieType 

ILInkl 

Author 

Mr John Smith lUnlinkI ILinkI 

Operations 

- 

State Machines 

Article. Authoring 

I Publish I 


9. Enter some information and click the "Submit Changes" button. 

1 0. Next to the ArticieType you will see a hyper link entitled "Link", this allows you to link the Article to an ArticieType, click 
this link now. 


5 







4.1 State machine operation 


ECO quick start 07 - Creating an 


ArticleType All classes 


Filter 


Results 


^ Page 1/1 -Objects 1-2 

Detail ID Name Link 
Detail 1 WinForm Link 
Details ASP .NET Link 

f Createl 


1 1 . You will now be presented with a list of ArticleType instances created earlier. Next to each item there is a hyperlink 
entitled "Link". Click one of these links. 

12. You will now be returned to the Article you were editing, the ArticleType has now been set. It is also possible to unlink 
objects by clicking the "Unlink" hyperlink. 


Roles 

ArticleType WinForm l UnlinkI I LinkI 

Author Mr John Smith f UnlinkULinkl 

Repeat these steps to create an article for the second Author instance. 


4.1 State machine operation 

At the bottom of the auto form for Article you may have noticed there is a section entitled "State Machines". Within this 
section there is a single button entitled "Publish". If you think back to the 4th article in this series (Creating a state machine) 
you will remember the state machine diagram for the Article class and how it behaved during prototyping. 



1 . Select the Author with AutoPublishArticles set to True. 
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2. At the bottom of the Author auto form you wiii see a Roies section entitied "Articies", ciick the "Detaii" hyperiink next to the 
articie in the iist. 

3. At the bottom of the Articie auto form you wiii see the State Machine section and a singie button entitied "Pubiish". 


state Machines 


Article. Authoring 


Publish 


4. Ciick the "Pubiish" button, the state of the Articie wiii change from Authoring to Pubiished, and the "Pubiish" button wiii be 
repiaced with an "Edit" button aiiowing you to put the Articie state back to Authoring. 

5. Now ciick the "Aii classes" hyperlink and then the "Show" hyperlink next to the Author class. 

6. This time click the "Detail" hyperlink next to the Author that has AutoPublishArticles set to False, then click the "Detail" 
hyperlink next to the Author's only Article. 

7. Scroll to the bottom of the page to where the State Machine section is located and click the "Publish" button. 


state Machines 
Article. Revievving 


Reviewing. Checkingspelling 


SpellingChecked 

Reject 


8. The state machine will now enter the Reviewing state, which according to the state machine diagram is a composite state 
containing two more states, "CheckingSpelling" and "CheckingGrammar". As you can see the generated HTML accounts 
for embedded regions too. 

9. Click the "SpellingChecked" button and it will be replaced with a button entitled "GrammarChecked". 

1 0. Now click the "Reject" button and the state will be set to "Rejected", in addition the Reason Rejected text box will read 
"Grammar". 



The Article will now be in a state where the Author can see that their article has been rejected and why, they can then put 
the article back into the Authoring state by clicking the "Edit" button. 
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5 New ECO ASP.NET components 

In ECO IV the interaction between objects in an EcoSpace and the web Ul controis is bandied by two new components. 


EcoSpaceManager 

This component makes an EcoSpace instance avaiiabie during the rendering of a web form, at the end of the rendering 
process this component wiii ensure that the correct action is taken to reiease the EcoSpace instance. This behavior depends 
upon a number of settings on the EcoSpaceManager and aiso in the web.config fiie. important properties of this component 
are: 


• ID: The unique name of this oomponent. 

• EcoSpaceTypeName: The drop down iist wiii present a iist of EcoSpace types avaiiabie in your projeot. In this case there 
wiii be oniy one, but it is possibie to have different types of EcoSpace in the same project with each having its own modei. 
When the EooSpace property of this component is read it wiii ensure that an EcoSpace of the specified type is returned. 

• SessionStateKey: The first time the EcoSpace property is read this component wiii first see if there is a key in the 
ASP.NET Session with the given name. If there is then the EcoSpace heid in the session with this key wiii be returned. 

• SessionStateMode: This setting specifies whether or not to piace the EcoSpace instance into the ASP.NET session at the 
end of the page render. 

• Aiways: The EooSpace instance wiii aiways be put into the session at the end of the page render. 

• IfDirty: The EcoSpace instance wiii be put into the session at the end of the page render oniy if it has dirty objects 
(modified persistent objects which have not been saved to the data storage.) 

• Never: The EcoSpace instance wiii not be put into the session, it wiii either be disposed of or piaced back into a pooi. If 
there are dirty objeots in the EcoSpace at the end of the page render an exception wiii be thrown. 
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EcoDataSource 

This component is responsibie for controiiing interaction between objects in the EcoSpace and the web Ui controis. It obtains 
its EcoSpace instance from an EcoSpaceManager. important properties of this component are: 


• AddDefauitProperties: If set to True then columns will be created automatically at runtime to represent the data made 
available by the Expression and PsExpression properties. If a column has been added at design time with a conflioting 
name then it will take precedenoe. 

• Add External Id: If set to True a column will be added named "Externalld" which provides read only aocess to a string 
which can be used to uniquely identify an instance of a modeled business class. This option is only valid if the result of 
evaluating the expressions results in a single business object or a collection of business objects. 

• DeleteMode: Specifies the action to take when the user clicks Delete on a new web control such as GridView: 

• Disallow: No aotion will be performed. 

• Delete: Deletes the selected object, this option is only valid if evaluating the Expression and PsExpression properties 
returns a single object or a collection of objects. 

• Unlink: The selected object will be removed from the list, this option is only valid if evaluating the Expression property 
returns a multi role, such as seIf.purchaseOrder.lines. 

• EcoSpaceManagerlD: Identifies which EcoSpaceManager to obtain an EcoSpaoe instance from during rendering of the 
web form. At design time this is used to identify the EcoSpace type and therefore the model information. 

• Expression / PsExpression: These expressions are exeouted automatioally during rendering of the web form. First the 
PsExpression is executed, and then the Expression is evaluated. If there is no PsExpression then the Expression is 
evaluated against the EcoSpace, otherwise it is evaluated against the result of executing the PsExpression. 
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• InsertMode: Specifies the action to take when EcoDataSource. Insert is executed. You should use the Insert so that 
ASP.NET is aware the binding list has changed. 

• Disallow: No action will be taken. 

• AddNew: Adds a new instance of the correct type to the collection. This is only valid if evaluating the expressions 
results in a collection of business objects, either Alllnstances of a class or a multi role member of a business object. 

• CreateNew: Always creates a new instance of the correct class type. 

• ManualUpdate: If set to False then any changes made via Insert / Delete / Edit will be updated to the data storage 
immediately. If set to True then no update will be performed, in which case the developer must call UpdateDatabase or 
ensure that the EcoSpaceManager.SessionStateMode is set appropriately to allow the page rendering process to finish 
with dirty objects. 

• MemberVisibility: Specifies the maximum exposure level of properties that will be added automatically when 
AddDefaultProperties is set to True. 

• NullRowMode: When the resulting element of evaluating the expressions is a collection this property specifies where to 
add an empty row representing NULL. This can be useful for example when you wish to present a list of objects for the 
user to choose a value from and you wish to allow them the option of selecting nothing. 

• None: No additional row will be added to the collection. 

• First: An additional row will be added to the top of the collection. 

• Last: An additional row will be added to the bottom of the collection. 

• IfEmpty: An additional row will only be added to the collection if the collection is empty. 

• SupportSorting: If set to True then web Ul controls that implement sorting will enable their sorting functionality. 

• ValidateRowOnInsert / ValidateRowOnUpdate : If set to True the ValidatingRow event will be executed, providing you 
with the option to validate the changes to the object before they are applied permanently to the local EcoSpace cache. 
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5.1 Logical flow 
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This diagram illustrates the life cycle of an ASPX page request from the point of view of the ECO ASP .NET compnents. 


When web L)l controls are data bound to an EcoDataSource they will attempt to read the data values of the component. If 
the data has not already been determined the EcoDataSource will execute its expressions like so 
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1 . Set the evaluation context to null (the EcoSpace.) 

2. If there is a PsExpression then execute it and set the evaluation context to the result of the execution. 

3. If there is an Expression then evaluate it in memory and set the context to the result of the evaluation. 

4. Set the resulting element (to data bind to) to the result context. 

In order to evaluate expressions etc the EcoDataSource requires an instance of an EcoSpace. To obtain this instance it will 
retrieve it from the EcoSpaceManager's EcoSpace property. To return an EcoSpace the EcoSpaceManager will go through 
the following process 

1 . If the EcoSpace property is not null then return the value immediately. The property will not be null if the EcoSpace 
property has already been read during the page rendering process. 

2. If SessionState is not set to Never, and there is an EcoSpace stored in the session under the specified key (the value 
entered into SessionStateKey) then return this value. 

3. If there are any EcoSpaces available in the pool (see the Web.config file for setting the pool size) then 

1 . Get an instance from the pool. 

2. If there is a SyncHandler on the PersistenceMapperProvider then get all changes made by other users and sync them 
into the EcoSpace's cache. 

3. Return the fetched EcoSpace. 

4. Otherwise create a new instance of the specified EcoSpaceTypeName will be created and returned. 

Subsequent access to the EcoSpaceManager. EcoSpace property will return the instance last returned. This value is held 
until the end of the page rendering process when the EcoSpaceManager is unloaded. At this point the EcoSpace manager 
will relinquish its reference to the EcoSpace and go through the following process 


1 . If the SessionState is set to Never 

1 . If the EcoSpace contains dirty objects then throw an exception. 

2. Otherwise return it to the pool. 

2. If the SessionState is Always 

1 . Put the EcoSpace into the session using the value in SessionStateKey as the key. 

3. If the SessionState is IfDirty 

1 . If there are dirty objects in the EcoSpace then put it into the session 

2. Otherwise return it to the pool. 

When returning an EcoSpace to the pool the EcoSpace will only be added back if the following conditions are true 


1 . The number of items in the pool is less than the maximum pool size in Web.config. 

2. The amount of time elapsed since the EcoSpace instance was created is less than the max age setting in web.config. 
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6 Creating a web form 


Using the new ECO components for web forms means that there is no need for any kind of speciaiized "ECO web page". 
Simpiy drop these new oomponents onto any existing web form and you are abie to aocess instances of your modeied 
ciasses. As an exercise we'il recreate an Eco WebForm compieteiy from scratch. This means that it is easy to make any 
existing web form abie to support ECO, or to use ECO on Web Form Content pages too. 

1. Deiete WebFormI .aspx 

2. Create a new Master Page to the projeot. 

3. Add a new Web Content Form to the project named "Authors". 

4. Seiect the master page. 

5. Set the new content page as the project's start page by right-ciicking it and seiecting "Set As Start Page". 

The foilowing steps wili add the ECO components to the content form to enabie it to access instances of your modeied 
ciasses. These same steps can be used for normai web forms and aiso existing web forms. 

6. Add an EcoSpaceManager to the content form. 

• Set its EooSpaceTypeName to OuickStartEcoSpace. 

• Note that the SessionStateKey wiil aiso defauit to the same vaiue. 

7. Add an EcoDataSource and set it's EcoSpaceManagerlD to EcoSpaceManagerl . 

• Set its ID to AuthorDataSource. 

• Set its EooSpaceManagerlD to EcoSpaceManagerl . 

• Use the [...] editor on the Expression property and set its Expression to 


Author .alllnstances 


Now the EcoDataSource (AuthorDataSource) has a unique identity, and a way of obtaining an EcoSpace and Eiement 
(business objects) at runtime. 


8. From the Data section of the component tooibox add a GridView controi to the form. 

• Set its ID property to AuthorGridView. 

• Set its DataSouroelD to AuthorDataSource. 

• Use the [...] editor on the Coiumns property to remove aii coiumns except for the foliowing 

• AutoPubiishArticies 

• Saiutation 

• FirstName 

• LastName 

• FuilName 

• EmaiiAddress 

• Password 
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• Rearrange the coiumns into the above order. 

• Ciick each coiumn in turn and give it an appropriate HeaderText property. 

• Ensure that the Readonly property for the FullName column is True. 

• Ciick the Tasks button at the top right of the GridView. 


Pa.s.word 

^1 GridView Tasks 

abc_123 


Auto Format... 


9. Seiect the Auto Format option on the popup window and choose a nice coior scheme. 

10. Before dosing the tasks window also set Enable Sorting to True. 

1 1 . Finaily on the AuthorGridView set both AutoGenerateEditButton and AutoGenerateDeieteButton to True. 

Now run the appiication again and you shouid see data from the database that was added earlier, if there are no instances 
of Author then you wiil see nothing, this is because the GridView controi does not output FITML if there is no data. 


Ciick the Edit column next to an Author and the Ul will change so that you may edit the information and then either click 
Update to keep your changes or Cancei to revert. 

elcome to mv ECO driven website 



Edit Delete Ivfr Fred Smith ^Fred Smith him@home.com secret 
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Adding new authors 

1 . Add a Button to the form beneath the AuthorGridView. 

2. Set its ID to NewAuthorButton. 

3. Set its Text property to New author. 

4. Set the button's Ciick event code as foiiows 


protected void NewAuthorButton_Click (object sender, EventArgs e) 
{ 

AuthorDataSource . Insert ( ) ; 

} 


Re-run the application and ciick the "New author" button, you wili see a new row appear. Click Delete to delete the new 
Author. Note that the Author is deleted immediately without confirmation, this wiil be addressed next. 


6.1 Confirming deietion 

Clicking the Deiete iink next to a row wiil delete the Author immediately. This is not ideal as it is quite easy to accidentaily 
click the wrong iink on a web page. A JavaScript confirmation box wiii now be added to ensure that the user realiy does wish 


13 






6.1 Confirming deletion 


ECO quick start 07 - Creating an 


to delete the row. 


1 . On the AuthorGridView set AutoGenerateDeleteButton to False. 

2. Use the [...] editor on its Columns property. 

3. In the Available Fields list at the top left of the form expand the tree node entitled "CommandField". 

4. Select the child node entitled "Delete" and then click the Add button. 

5. Use the arrows to rearrange the Deiete column so that it is at the top of the "Seiected fieids" list, this wili ensure it appears 
along side the Edit button. 

6. With the Deiete button seiected click the link entitied "Convert this fieid into a TemplateFieid" at the bottom right of the 
form. 
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7. Ciick the OK button. 

8. Now switch the editor to the Source view. 

9. Look for a node named LinkButton in the following path 


<body> 

<f orm> 

<asp : GridView> 

<Columns> 

<asp : TemplateField> 
<ItemTemplate> 

<asp : LinkButton> 


10. Change the LinkButton's ID to DeleteAuthorLinkButton. 

1 1 . Now switch back to the Design view and in the AuthorGridView. RowDataBound event add the foilowing code. 


protected void AuthorGridView_RowDataBound (object sender, GridViewRowEventArgs e) 
{ 

LinkButton DeleteButton; 

if (e . Row . RowType == DataControlRowType . DataRow) 

{ 
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DeleteButton = e . Row . FindControl ( "DeleteAuthorLinkButton" ) as LinkButton; 
DeleteButton . OnClientClick = "return conf irm ( ' Are you sure you want to delete this 
author? ' ) ; " ; 



Now run the application again and click the Delete link. A dialog box will appear asking you if you are sure you wish to delete 
the author. Clicking Cancel will abort the deletion, whereas clicking OK will continue as before. 


elcome to mv ECO driven website 


Auto publish Salutation First name Last name Full name Email address Password 


Edit Delete 
Edit Delete 
Edit Delete 
I New Author | 

I Cancel | 


Mr John Smith Mr John Smith me@home.com secret 

Mr Fred Smith Mr Fred Smith him@home.com secret 


The page at http://localhost;1235 says: 


m 


& 


Are you sure you want to delete this author? 


6.2 Validating user input 


6 


This next topic will implement validation for user input. Before allowing the EcoSpace to update the data storage the OCL 
constraints entered against the class in the model will be evaluated. For each broken constraint an error message will be 
displayed on the form. If there are any broken constraints the update will not be permitted. 


Creating a static validator class 

1 . Create a new class by right-clicking on "QuickStart.Asp" and selecting the menu item Add->New Item and selecting 
"Class". 

2. Name the class StaticValidator. 

3. The implementation of the class is as follows 


public class StaticValidator : object, IValidator 
{ 

private readonly string errorMessage; 

public StaticValidator (string errorMessage) 

{ 

this . errorMessage = errorMessage; 

} 

string IValidator . ErrorMessage 
{ 

get { return errorMessage; } 
set { } 

} 

bool IValidator . IsValid 
{ 
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get { return false; } 

set { } 

} 

void IValidator . Validate ( ) 

{ 

} 


Using this class it is possible to add error messages which will appear in the ASP.NET ValidationSummary control with the 
following code 


Page . Validators . Add (new StaticValidator ( "This is an error message")); 


Creating a PageHelper class 

As validation is likely to be performed on multiple pages it makes sense that the code to perform the validation should be in a 
utility class. 
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1 . Add DroopyEyes.Eco. Validation to the References of your QuickStart.ASP projeot. This file can be found in your 
{Program Files}\CapableObjects\ECO\5.0\Bin folder. 

2. Create a new class. 

3. Name it PageHelper. 

4. The implementation of the class is as follows: 


using System. Collections . Generic; 

using System . Web . UI ; 

using Eco . Ob jectRepresentation; 

using Droopy Eyes . EcoExtensions . Validation; 

namespace Quicks tart 

{ 

public static class PageHelper 

{ 

public static bool ValidatePage (Page currentPage, lOb jectinstance af fectedOb ject ) 

{ 

//Create a list to hold the constraints 

List<IConstraint> constraints = new List<IConstraint> ( ) ; 

//Use the DroopyEyes ModeledConstraintProvider to get constraints from the 

model 

ModeledConstraintProvider constraintProvider = new 
ModeledConstraintProvider ( ) ; 

bool tempResult = true; 

//Get all constraints for the object 

constraintProvider . GetConstraintsForOb ject (af fectedOb ject, constraints) ; 

//Create a StaticValidator for each broken constraint 
foreach (IConstraint c in constraints) 

{ 

if ( ! c . IsValid) 

{ 

StaticValidator v = new StaticValidator (c .Name) ; 
currentPage .Validators .Add (v) ; 
tempResult = false; 
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return 


tempResult ; 


Validating input 

The EcoDataSource has two properties of relevance ValidateRowOnInsert and ValidateRowOnUpdate. If these are True the 
EcoDataSource's ValidatingRow event will be triggered whenever a new object is inserted or updated using the 
EcoDataSource. This event allows the user to implement code which can determine whether or not the changes are valid 
and, if not, cancel the update. If the update is canceled an exception will be thrown. Validation will be added for updates only: 


protected void AuthorDataSource_ValidatingRow (object sender, 
Eco . Web . UI . WebControls . E coDat aS our ceOb ject Event Args e) 

{ 

if ( ! PageHelper . ValidatePage (Page, e . Af fectedOb ject) ) 
e. Cancel = true; 

} 
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An exception being thrown when the user tries to enter invalid data is undesirable. Therefore the EcoDataSource has a 
method IsValidNewValues which does the following 


1 . Starts an in-memory transaction 

2. Applies the new values to the object instance 

3. Triggers the ValidatingRow event to allow the page to determine whether or not the changes are valid 

4. Rolls back the in-memory transaction 

5. Returns the result of ValidatingRow 

When the GridView control is about to update the values of a row it will execute its RowUpdating event. This event contains 
information about the change such as a collection of the new values. Using this information it is possible to ask the 
EcoDataSource if the new values are valid as described above 


protected void AuthorGridView_RowUpdating (object sender, GridViewUpdateEventArgs e) 
{ 

if (! AuthorDataSource . IsValidNewValues (e . Keys , e . NewValues ) ) 
e. Cancel = true; 

} 


If the EcoDataSource says the new values are not valid then the GridView will cancel its update. This prevents the GridView 
from leaving the Editing mode and more importantly prevents it from attempting to update the EcoDataSource and therefore 
avoiding the exception. 


Testing the validation 

Add a ValidationSummary control to the form from the tool palette. Then run the application again, edit an author and try to 
update the row with an invalid email address. Instead of allowing the author to be updated the page will display an error 
message and prevent the update from taking place. 
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elcome to mv ECO driven website 


Email address required 


Auto Dublish Salutation 


First name 


Email address 





John 

iFred 


Smith 

ISmith 


Mr John Smith me(^ 


secret 


■secret 


This approach to validation is particularly valuable because object validity is determined by the business model, and 
therefore the same rules may be applied across all user interface implementations. 


If you re-run the application and try to add a new Author by clicking the "New Author" button you will encounter a 
RowValidationFailedException. This is because the AuthorDataSource.ValidatingRow event is used for both updates and 
inserts. When you click the NewAuthorButton the method AuthorDataSource.lnsert() is executed which creates a new 
instance of the Author class, but as its properties are all empty the new object fails validation. 


There are a number of ways of dealing with this situation. 

1 . Set AuthorDataSource.ValidateRowOnInsert to false. No validation will be performed when AuthorDataSource.lnsert() is 
executed. 

• PRO: Very simple solution. 

• CON: You have to rely on the user click Edit after adding a new Author in order to make the Author contain valid 
values. 

2. Ensure that the Author class has suitable default values on its UML attributes. 

• PRO: Another simple solution. 

• CON: The Author class requires a unique email address per Author. 

• CON: You cannot default these details with the correct values. 

3. Change the NewAuthorButton. Click method like so: 
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Author newAuthor = new Author (EcoSpaceManagerl . EcoSpace) ; 

newAuthor . AutoPublishArticles = false; 

newAuthor . Salutation = "Mr"; 

newAuthor . FirstName = "Peter"; 

newAuthor . LastName = "Morris"; 

newAuthor . EmailAddress = "me0home.com"; 

newAuthor . Password = "secret"; 

EcoSpaceManagerl . EcoSpace . GetEcoService<IPersistenceService> ( ) . UpdateDatabase (newAuthor) ; 
AuthorGridView . DataBind ( ) ; 


• PRO: It works. 

• CON: The default values cannot be expected to be correct. 

• CON: It bypasses the validation, so the values you enter might actually be incorrect once the constraints on the Author 
class change. 

4. Create a secondary form for creating new Author instances. 

• PRO: The Author is created from user entered values. 

• PRO: The object wont be saved unless it passes validation. 
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6.3 Exercise for the reader 
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• CON: it requires deveiopment of an additionai form. 


6.3 Exercise for the reader 


Create a new web form to enabie you to add or remove articie types (ArticieType ciass.) Make sure you add vaiidation so 
that users cannot enter invaiid data and confirm deietion when the user ciicks the Deiete link. 
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7 Passing objects between page 
requests 


Seiecting an item from a iist and then redirecting the user to a page that manipuiates the seiected item in some way is a very 
common website feature. This next exampie wiii show how to seiect an author on the main page and then show the author's 
articies. Afterwards another page wiii be added to deai with adding and editing articies. 


Creating a link in the GridView control 

1 . Edit the coiumns on AuthorGridView. 

2. Add a Hyperlink coiumn. 

• Set Text to Articies. 

• Set DataNavigateUriFieids to ID 

• Set DataNavigateUriFormatString to 


Author Art ides . aspx?AuthorID= { 0 } 


Now run the appiication again and ciick the Articies iink next to an author, you wiii see that you are redirected to 
http://localhost:8080/AuthorArticles.aspx?Author=1, which at the moment wiii dispiay a Page Not Found error. 


Creating the target page 

1 . Create a new Web Content Form AuthorArticies 

2. Add an EcoSpaceManager component 

• Set its EcoSpaceTypeName property 

3. Add an EcoDataSource component 

• Set its ID to Article DataSou roe 

• Set its EcoSpaceManagerlD to EcoSpaceManagerl 

5. Use the [...] editor on ArticieDataSource's Parameters property 

• Click the Add Parameter button 

• Name the parameter param_AuthorlD - you may edit the name by singie ciicking the parameter name in the grid 

• Set the parameter's Parameter Source to QueryString 

• Set the Query String Fieid to AuthorlD 

• Click the "Show advanced properties" hyperiink to expose more properties 

• Change "Type" to Int32 

• Click OK 

6. Set the ArticieDataSource.PsExpression property to the foilowing OCL expression 


Author . alllnstances->select ( ID = param_AuthorID) .Articles 
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Note: param_AuthoriD is case sensitive. 

6. Add a GridView to the form 

1 . Set its ID to ArticieGridView 

2. Set its DataSource ID to ArticleDataSource 

3. Use the [...] editor on Coiumns so that you have oniy the foiiowing coiumns. 

• Titie 

• State 

• ArticieType 

If you have articles in your database from running your Winforms appiication you wili see them iisted on the page. This is 
how the process works. 


Default.aspx 


1 . When the iist of authors is dispiayed on Authors. aspx it wiii render a coiumn named "Articies". 

2. This coiumn is a Hyperlink coiumn, its iink is the uri defined by DataNavigateUriFormatString. 

3. DataNavigateUriFormatString is the string to be parsed in order to produce the finai URL. To produce the finai vaiue it is 
passed to the .NET String. Format() method, aiiowing for runtime parameters to be injected into the string using 
piacehoiders such as {0}, {1}, {2}. 

4. DataNavigateUriFieids contains a iist of coiumn names on the GridView's data source (AuthorDataSource). The {0}, {1}, 

{2} etc are repiaced with the vaiue of these coiumns. In this exampie {0} is repiaced with the ID of the author, giving the 
vaiue Author=1 

AuthorArticles.aspx 



1 . The page is rendered, this causes the ArticieGridView to render. 

2. The ArticieGridView requires data to bind to, so this data is retrieved from its data source (ArticieDataSource). 

3. ArticieDataSource sees that it has a Parameter named "param_AuthorlD", so it creates an OCL variabie with the same 
name. 

4. The ArticieDataSource then sets the vaiue of this variabie as instructed; it sets it to the vaiue of the AuthorlD vaiue in the 
URL query string. 

5. ArticieDataSource evaiuates its PsExpression and Expression in turn. 

6. The PsExpression resuits in ail authors with the specified ID (of which there can be oniy one) and returns that author's 
articies. 

Note: PsExpression was used instead of Expression so that the data fiitering is performed in the database instead of ioading 
aii Author instances into memory and fiitering. 

EcoDataSource. Parameters may be used to define OCL variabies from a number of sources. This wili be demonstrated 
further when a master detaii exampie is created. 


21 




8 


ECO quick start 07 - Creating an 


8 Editing a singie object 


So far ail editing has been performed as a iist of objects in a GridView controi. It is common for websites to aiiow the editing 
of singie objects on a page, providing a more compiex page iayout with controis such as embedded word processing for 
editing articie oontents for exampie. This next exampie wiii show how to oreate a web form of this type. 


Creating a link to the new page 

Add a new column to the ArtioleGridView in AuthorArtioies.aspx. The coiumn shouid be a Hyperlink coiumn with the 
foilowing settings 


• Set its Text to Edit 

• Set its DataNavigatellriFieids to ID 

• Set its DataNavigateUriFormatString to EditArticie.aspx?ArtioielD={0} 

Creating the target page 

1 . Add a new Web Content Form named EditArticie 

2. Add an EcoSpaceManager and set its EooSpaceTypeName property 

3. Add an EcoDataSource 

• Set ID to "ArtioleDataSource" 

• Set its EcoSpaceManagerlD 

4. Add a new Parameter to the ArticieDataSouroe 

• Set its Name to param_ArticielD. 

• Set its Parameter Source to QueryString. 

• Set its Query String Fieid to ArticieiD. 

• Click "Show advanced properties". 

• Change "Type" to Int32. 

5. Set the ArticieDataSouroe. PsExpression to 
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Article . alllnstances->select ( ID = param_ArticleID) 


6. Evaiuations performed in the database using PsExpression must aiways return a coiiection of objects, even if there is only 
one item in the coiiection. To obtain a reference to oniy a singie artioie we must add an OCL expression to the Expression 
property which wiii then be evaiuated against the resuit of the PsExpression evaiuation. Set 
ArtioieDataSource. Expression to 


self->f irst 


Note: "seif" (which is case sensitive) refers to the eiement returned by evaiuating PsExpression, which in this case is a 
Coiiection(Articie). 
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7. From the Data category in the tooibox add a FormView control to the form. 

• Set its ID to ArticleFormView 

• Set its DataSourcelD to ArticleDataSouroe 

Now run the applioation. Select the Articles link against an author, and then the Edit link against an article, you will now see 
a read only display of the article selected with Edit, Delete, New links at the bottom. 


Editing the article 

As we intend to have the user edit the article rather than viewing it (a separate ShowArticle.aspx would make more sense in 
this case anyway) we need to ensure that ArticleFormView goes immediately into Edit mode when the page is shown. In 
addition we will remove the View template. 


1 . Right-olick ArticleFormView and from the context menu seleot the Edit Template->ltem Template item. 


Cut 

Copy 

Paste 

Paste Alternate 

Delete 

Style.., 

View Code 

View Component Designer 


Show Smart Tag 
Auto Format.,. 



Edit Template ► 

ItemTemplate 


Refresh 

Properties 


FooterTemplate 

EditItemTemplate 

InsertItemTemplate 



HeaderTemplate 

EmptyDataTemplate 

PagerTemplate 


Ik A 

X 
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2. The control will now allow you to edit the Item Template, which is the view you see by default. Seleot all of the controls 
within the Item Template area and delete it. 


luisuurLC * Hruueuai.d3uurLB 


^ormViewl - ItemTemplate 



1 ItemTemplate 


1 



3. Perform the same steps for InsertItemTemplate. 

4. Now right-click the control again and select EditItemTemplate from the context menu. 

5. Again select all of the controls within the template area and delete them. 
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6. Now add a tabie to the tempiate's ciient area, edit the tabie so that it iooks something like the following illustration. 


■ormViewl - EditItemTemplate 


EditItemTemplate 



Title 

Alniu state 


Re\iewiiig state 

Desciiptioii 

Both- 



You may wish to copy / paste the following HTML into the ASPX file 


<Edit ItemTemplate> 

<table border="l"> 

<tbody> 

<tr> 

<th>Title</th> 

<tdx/td> 

</tr> 

<tr> 

<th>Article type</th> 
<tdx/td> 

</tr> 

<tr> 

<th>Main state</th> 
<tdx/td> 

</tr> 

<tr> 

<th>Reviewing state</th> 
<tdx/td> 

</tr> 

<tr> 

<th>Description</th> 

<tdx/td> 

</tr> 

<tr> 

<th>Body</th> 

<tdx/td> 

</tr> 

</tbody> 

<tfoot> 

<tr> 

<td colspan="2 "x/td> 
</tr> 

</tfoot> 

</table> 

</Edit ItemTeraplate> 
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7. From the Web Controls oategory in the tool palette add a TextBox to the cell to the right of the cell entitled "Title". When 
the text box is added you will see a Tasks window. 
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8. Ciickthe Edit DataBindings iink. 

9. In the form that appears 

• Ensure that the Text property is seiected in the iist on the ieft. 

• Seiect the "Fieid binding" radio button. 

• Set "Bound to" to Titie. 

• Ensure that Two-way databinding is checked. 

• Click OK. 



10. Sometimes these radio buttons wiil not be enabied, if you experienoe this you shouid perform the foiiowing steps instead. 

• Ensure that the Text property is seiected in the iist on the ieft. 

• The Custom binding radio button wiil be enabled by default. 

• In the Code expression text box enter Bind("Title") 

• Click OK. 

1 1 . Set the ID of the text box to TitleTextBox and its MaxLength to 64. 

12. Now add text boxes for Desoription and Body, ensuring that you set the TextMode properties to Multiline, and that you 
set the MaxLength of Description to 255. 

For the State add Label controls instead, and data bind it using the same technique. 


Saving or cancelling changes 

To add the ability to save or cancel changes two LinkButton controls will be added. 
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1 . Add a LinkButton. 

• Set its ID to UpdateLinkButton 

• Set its Text to [Update] 

• Set its CommandName to Update 

2. Add another LinkButton. 

• Set its ID to CancelLinkButton 

• Set its Text to [Cancel] 

• Set its CommandName to Cancel 

• Set its OnClientClick property to 


return confirm ( "Are you sure you want cancel your changes?"); 


3. We need to ensure that the form view automatically goes into edit mode when the page is displayed. Select the 
ArticleFormView control and set its DefaultMode property to Edit. 

4. To return to the author's list of articles once the changes have been saved or canceled add the following code to 
ArticleFormView. ModeChanged: 


protected void ArticleFormView_ModeChanged (object sender, EventArgs e) 

{ 

lOclPsService oclPsService = 

EcoSpaceManagerl .EcoSpace.GetEcoService<IOclPsService> () ; 

string ocl = string . Format ( "Article . alllnstances->select ( ID= { 0 }). Author " , 

Request . Querystring [ "Articleld" ] ) ; 

IList<Author> Authors = oclPsService . Execute (ocl ). GetAsIList<Author> () ; 

Response . Redirect (string . Format ( "AuthorArt ides . aspx?AuthorID= { 0 } " , Authors [ 0 ] .ID) ) ; 

} 


Note that this requires you to add the following name spaces to your "using" clause. 

• System. Collections.Generic 

• QuickStart.Model 

• Eco. Services 

Run the application and navigate to an article. You will see that Ul is populated with the values of the selected article. You 
may modify these values and then click either Update or Cancel. 
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8.1 Databinding a dropdown iist 

Next a drop down list will be added to the EditArticle form. This drop down list will present the user with a list of all available 
ArticleType instances from which the user may choose the correct type for the current article. By default the current 
Article. ArticleType should be selected in the drop down list and when the user clicks the Update link the article should be 
updated accordingly. 


1 . Add an EcoDataSource to the form 

• Set its ID to ArticleTypeDataSource 

• Set its EcoSpaceManagerlD to EcoSpaceManagerl 
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• Set NullRowMode to First. This will add an empty row at the top of the list of article types so that null values may be 
represented 

• Set its Expression to 


ArticleType . allInstances->orderBy (name) 


2. Right-click the FormView control and edit the EditItemTemplate 

3. Add a DropDownList to the cell to the right of the label "Article type" 
• On the Tasks window select Choose Data Source 


?ormvie^ 


EditItemTemplate 


EditItemTemplate 


Title 

Aiticle 


IMaiii state 


ii ^' ; ; DropDownList Tasks 

Ijatabound v 

1 T, — Edit DataBindinQs . , 


%lMainState] choose Data Source. . 


. . I Edit Items... 

E„^b|eAut0P05t^ 


Data Source Configuration Wizard 




Choose a Data Source 


Select a data source: 


ArtIcleTypeDataSource 


Select a data field to display in the DropDownList; 


Name 


Select a data field for the value of the DropDownList: 


ExternallD 
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• Set the data source to ArtIcleTypeDataSource 

• Set the display field to Name 

• Set the value field to Externalld 

• Set its ID to "ArticleTypeDropDownList" 

This will populate the drop down with a list of all article types in the data storage. It will display the Name of each, but the 
SelectedValue property will return the Externalld of the object. 


Note: The Externalld is a reference to an instance of a modeled class, presented in the form of a string. The Externalld is will 
not change during the life of the web application, however it may change when your model is modified. It is recommended 
that you do not use Externalld in URLs which may be spidered by a search engine. 


These steps will present a drop down list of all ArticleType instances. The "Name" will appear in the list and the "ExternallD" 
will be used in the HTML to identify the object's value. Next the drop down will be linked to the current Article's ArticleType 
property. In addition the Article will be updated with the newly selected value when the Update link is clicked. 
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Updating the article's property 

The web form will use the current Article as the binding context for the drop down, this is because it is parented within a 
FormView which has its DataSourcelD set to ArticleDataSource. As a consequence all that is required is to specify which 
column the current value should be data bound to. 


1 . On the Tasks window for the drop down list select Edit DataBindings 

2. In the bindings form ensure that SelectedValue is two-way bound to ArticleType 

Note: If only the Custom Binding radio button is enabled you should enter Bind("ArticleType") as the expression. 


There is one final step to perform. When the user interfaces attempts to set the default selected item in the drop down list it 
will attempt to locate Article.ArticleType in a list of Externalld's, however, columns created automatically by the 
EcoDataSource to represent single-role associations (links to a single ECO object) are added with the following expression 


self .ArticleType . as St ring 


The purpose of this is to enable the object to be displayed in a grid etc as a meaningful piece of text such as "Mr Peter 
Morris". Unfortunately this is incompatible with what we are currently trying to achieve. Not only do we not want to see the 
default string representation of the article type, we do not want the object reference either. What we need is a way to read 
and write the value as an Externalld string. 


1 . Use the [...] editor on the ArticleDataSource columns property. 

2. In the form that appears click the Add button to add a new column. 

3. Name the new column ArticleType 

4. Set its expression to self. ArticleType 

5. Set AsExternalld to True 
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Note: When columns are created automatically at runtime the ArticleDataSource will see that a column named "ArticleType" 
already exists and will skip creating the column automatically. 
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Now when the article type drop down list's default value is determined it will read the ArticleDataSource.ArticleType column 
and find a string. This string represents the Externalld of the referenced ArticleType (E.g. 12I34). When a new value is 
selected in the drop down list and the Update button is clicked the value of ArticleDataSource.ArticleType will be set to 
ArticleTypeDropDownList.SelectedValue, which will be the Externalld for the currently selected article type. 
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9 Master / detail 


This exampie wiii demonstrate how to oreate master / detaii reiationships. Seiecting an Author in a master grid wiii reveai aii 
reiated Artioies in a second grid. 


Adding the master grid 

1 . Create a new Web Content form to the Admin foider. 

2. Name the new item MasterDetaii.aspx. 

3. Add an EcoSpaceManager and EcoDataSource, and configure them appropriateiy. 

4. Edit the EcoDataSource 

• ID = AuthorDataSource 

• Expression = Author. aiilnstanoes 

5. Copy the AuthorGridView from Authors. aspx and paste it into the form, make sure you oiear out the events for the grid in 
the object inspector 

• AutoGenerateSeiectButton = True 

• AutoGenerateEditButton = Faise 

• Remove the Deiete coiumn 

• Remove the Artioies coiumn 


Adding the detail grid 

Now we have a read oniy grid showing aii existing authors, next a chiid grid wiii be displayed showing all articles for an 
author whenever the Select column next to an author is clicked. 


1 . Add another EcoDataSource to the form 

• ID = ArticleDataSource. 

• EcoSpaceManagerlD = EcoSpaceManagerl 

Now to make the ArticleDataSource aware that it is a child of the selected author. 

2. Use the [...] editor on the Parameters property and add a parameter 

• Name = param_AuthorExternallD - you may single-cliok the name in the grid to edit it if you wish to change it. 

• Parameter source = Control. 

• Control ID = AuthorGridView 

3. Edit the ArticleDataSource's Expression property and enter the following OCL 
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Author . ob jectfromExternalld (param_AuthorExternalID ) . articles 


Note: param_AuthorExternallD is case sensitive. 

4. Add a GridView to the form 
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• ID = ArticleGridView. 

• DataSourcelD = ArticieDataSource 

• Edit the coiumns and remove aii coiumns except for the foiiowing 

• Titie 

• State 

• ArticleType 

5. Add the foiiowing impiementation for the AuthorGridView's SeiectedIndexChanged event 


protected void AuthorGridView_SelectedIndexChanged (object sender, EventArgs e) 
{ 

DataBind ( ) ; 

} 


Now run the appiication. You shouid now have a working Master / Detaii page. 


AA elcoiiie to iiiv ECO driven website 



Select Mr Fred Smith MrFredSmitii him@home.com secret 


Title MainState ReviewState ArticleType 


My first article Reviewing CheckingSpelling C# 

My second article Aufiioring WinForms 
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10 Authorization 


Restricting access to certain parts of your website required two things, authentioation and authorization. Authentication is the 
stage where the user identifies themseif, authorization is the stage that occurs before every request which uses the 
information from the authentioation stage to determine whether or not to permit access to the requested resource. 


Impiementing authentication / authorization is reaiiy no different in an ECO driven website. This part of the document is 
inciuded partiy to demonstrate how to consume some ECO services in code rather than depending on the 
EcoSpaceManager and EcoDataSource oomponents. 


1 . First the MasterPage for the website needs a VaiidationSummary controi on it. If you have one on any of your other forms 
remove them. 

2. On the Author ciass add a new UML Attribute 

• Name = IsAdministrator 

• Type = booi 

• Initiai vaiue = faise 

3. Generate source code for the modei. 

4. Rebuiid the soiution. 

5. Use the Persistence Mapper Provider to evoive the DB if not using XML as your persistence. 

A change is now required to aiiow you to speoify that some Authors are administrators. 


6. Open the designer for Authors. aspx. 

7. Edit the Coiumns on AuthorGridView and add a CheokBoxFieid databound to IsAdministrator. 

8. Run the website and ensure at ieast one of your Author instances is marked as an administrator. 
Next the Web.Config fiie wiil be changed to enabie Forms authentication. 


9. Edit the Web.Config fiie. 

10. Looate the <authentication> node and change it as foiiows: 


Outhentication mode="Forms"> 

< forms 

name="ECOQuick St art Cookie" 
loginUrl=" /Login . aspx" 
protection="All " 
timeout=" 180 " 

/> 

</ authentication> 
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This enabies Forms authentioation, and additionaiiy specifies the URL to the iogin page. Next the Login page wili be created. 


1 1 . Create a new Web Content page. 

12. Name it Login. aspx. 

13. Add a TextBox and name it EmaiiAddressTextBox. 
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14. Add a TextBox and name it PasswordTextBox. 

15. Add a Button and name it LoginButton. 


<table> 

<tbody> 

<tr> 

<th>Email address</th> 

<td> 

<asp : TextBox ID="EmailAddressTextBox" runat="server"x/asp : TextBox> 

<asp : RequiredFieldValidator ID="EmailAddressRequiredValidator " 

runat= "server" 

ControlToValidate="EmailAddressTextBox" ErrorMessage=" Email address 
required" >Required</ asp : RequiredFieldValidator> 

</td> 

</tr> 

<tr> 

<th>Password</th> 

<td> 

<asp: TextBox ID="PasswordTextBox" runat="server" 

TextMode= "Pas sword" ></ asp : TextBox> 

<asp : RequiredFieldValidator ID="PasswordRequiredValidator " runat=" server " 
ControlToValidate=" PasswordTextBox" ErrorMessage=" Pas sword 
required" >Required</ asp : RequiredFieldValidator> 

</td> 

</tr> 

</tbody> 

<tfoot> 

<tr> 

<td colspan="2" /> 

<asp:Button ID="LoginButton" runat="server" onclick="LoginButton_Click" 
Text="Login" /> 

</tr> 

</tfoot> 

</table> 


Now the HTML has been added to aiiow the user to input their emaii address and password the ECO components wiil be 
added to aiiow these credentiais to be checked. 


1 6. Add an EcoSpaceManager to the form, and set its EcoSpaceTypeName property. 

1 7. Add an EcoDataSource component to the form 

• Name = AuthorDataSource 

• EcoSpaceManagerlD = EcoSpaceManagerl 

18. Edit the Parameters for AuthorDataSource. 

1 9. Add a new parameter 

• Name = param_EmaiiAddress 

• Parameter source = Controi 

• Countroi iD = EmaiiAddressTextBox 

20. Add another new parameter 

• Name = param_Password 

• Parameter source = Controi 

• Controi iD = PasswordTextBox 

Now some code-behind is required to iook up the Author with the given emaii address and password. 
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protected void LoginButton_Click (object sender, EventArgs e) 

{ 
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//Only continue if the ASP validators permit it 
if (Page . IsValid) 

{ 

//Iterate through all Authors returned by the EcoDataSource 
//there will be zero or one only 
Author author = null; 

foreach ( lElementProvider currentElementProvider in AuthorDataSource . Select () ) 
author = currentElementProvider . Element . GetValue<Author> () ; 


if (author == null) 

{ 

//Report the fact that the authentication failed 

Page . Validators . Add (new StaticValidator (" Invalid email address or 

password" ) ) ; 

Page . Validate ( ) ; 

} 

else 

{ 

//Get the ExternallD service 
lExternalldService externalldService = 

EcoSpaceManagerl . EcoSpace . GetEcoService<IExternalIdService> ( ) ; 

//Get the ExternallD for the author 

string currentUserExternalld = externalldService . IdForObject (author) ; 
//Store it in the session 

Session [ "CurrentUserExternallD" ] = currentUserExternalld; 

//Notify ASP that the login was successful, and give the author ExternallD 
as the user ID 

FormsAuthentication . RedirectFromLoginPage (currentUserExternalld, false) ; 

} 



The ExternailD (Author PrimaryKey) is used as the user's identity, and this ID is aiso stored in the Session so that pages can 
obtain a reference to the user. At the moment there is no protected content on the website. 


Restructuring the website 

1 . Create a new foider named "Admin". 

2. Move the foiiowing web forms into this foider 

• AuthorArticies.aspx 

• Authors. aspx 

• AutoForm.aspx 

• MasterDetaii.aspx 

3. Create a new foider named "Members". 

4. Move the foiiowing web forms into this foider 

• EditArticie.aspx 

5. Change the markup for AuthorArticies.aspx so that the URL reference to EditArticle now has the path 
/Members/EditArticle.aspx. 

6. Change the code-behind of EditArticle.es so that the URL redirected to has the /Admin/ path at the beginning. 
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Adding authorization 

Next the pages within the Members and Admin foiders wiil be protected from anyone who is not signed in. 
1 . Edit the Web.Config fiie, beneath the <configuration> node add the foiiowing 
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<location path="Members"> 
<system . web> 

<authorization> 

<deny users="?"/> 
</ authorization> 

</ system . web> 

</location> 

<location path="Admin"> 
<system.web> 

<authorization> 

<deny users="?"/> 
</ author iz at ion> 

</ system . web> 

</location> 


2. Set /Admin/Authors. aspx as your website's default start page. 

3. Run the application. 

4. You will now be redirected to the Login page. 

5. Enter an invalid email / password and you will see the error message telling you that your information is incorrect. 

6. Enter a valid email / password and you will be redirected to the Authors.aspx page. 


10.1 Role based authorization 


The authorization so far will allow any user access to the Admin folder. Next access to this folder will be restricted to those 
Author's who have IsAdministrator set to True. 


1 . Add an attribute to the Author class: IsAdministrator: Boolean 

2. Change the Web.config file so that the authorization section for the Admin folder reads as follows 


<location path="Admin"> 
<system.web> 

<authorization> 

<allow roles="Adrain" /> 
<deny users="*"/> 
</authorization> 

</ system . web> 

</location> 
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Note: You must allow the role "Admin" before denying access to all users 


If you now try running the application you will see that you cannot access the Admin folder at all. To define which roles the 
current user has a change is required in the Global. asax file. 


2. Edit the Global. asax file and add the following method 


void Application_AuthenticateRequest (object sender, EventArgs e) 
{ 
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if (HttpContext . Current . User != null) 

{ 

//Only support Forms authentication 

if (HttpContext . Current . User . Identity . AuthenticationType != "Forms") 

throw new Exception ( "Only forms authentication is supported, not " t 
HttpContext . Current .User. Identity. AuthenticationType ) ; 

//Get the ExternallD of the current user (if any) 

System . Security . Principal . Ildentity userid = 

HttpContext . Current . User . Identity; 

//Do we have some roles to retrieve? If so, replace the user object 
if (userid. Name != null) 

{ 

//Get a new EcoSpace 

QuickStart . QuickStartEcoSpace ecoSpace = new QuickStart . QuickStartEcoSpace ( ) ; 
ecoSpace .Active = true; 

//Get the External ID Service 

Eco . Services . lExternalldService externalldService = 
ecoSpace . GetEcoService<Eco . Services . IExternalIdService> ( ) ; 

//Get the author 
QuickStart . Author author = 

externalldService . Ob jectForld (userid . Name) . Get Value<QuickS tart . Author> ( ) ; 
if (author != null) 

{ 

System. Collections . Generic . List<string> roles = new 
System. Collections . Generic . List<string> ( ) ; 

roles .Add ( "Member" ) ; 
if (author . IsAdministrator) 
roles. Add ( " Admin " ) ; 

//Replace the user with our new user, including their roles. 

HttpContext . Current . User = new 

System .Security . Principal . Gene ricPrincipal (userid, roles. ToArray ( ) ) ; 

} 

} 

]//user != null 

} 


3. Add a new Default. aspx Web Content form to the root of your project with the two following links 


<a href=" /Members/MyArticles . aspx">My articles</a> 
<a href =" / Admin /Authors . aspx" >Authors</a> 
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4. Re-run the application and click the MyArticles link (this page does not yet exist). 

5. You will be presented with a login page, sign in as the non-administrator Author. 

6. You will not be permitted to access /Members/MyArticles. aspx which will show you a not-found error. 

7. Now go back to /Default.aspx and click the Authors link. 

8. You will be directed to the Login page again, this is because you need to log in as an administrator to see this page. 
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10.2 Accessing the current user 

Previousiy you created a Defauit.aspx page with a iink to a page /Members/MyArticies.aspx which did not exist. This page 
wiii be created next in erder to demonstrate how to access the user currentiy iegged in. 


1 . Create a new Web Content form in the Members foider named MyArticies.aspx. 

2. Add an EcoSpaceManager and EcoDataSource and configure them appropriateiy. 

3. Name the EceDataSeurce "ArticieDataSeurce". 

4. Edit the Parameters ef ArticieDataSeurce and add a parameter 

• Parameter source = Sessien 

• Session fieid = CurrentUserExternailD 

5. Set the Expression property to the foiiowing OCL expressien 


Author . ob jectfromExternalld (param_CurrentUserExternalID) .Articles 


6. Add a GridView (ArticiesGridView) te the form and connect it to the AuthorDataSource cempenent. 

7. Add a HyperLinkFieid ceiumn te the grid 

• Text = Edit 

• DataNavigateUriFieids = ID 

• DataNavigateUriFormatString = EditArticie.aspx?ArticielD={0} 

If you now re-run the application and click the "My articies" iink on the main page you wiii be prompted to sign in. Once 
signed in you wiii be presented with a term showing the articies of the Auther who's credentiais you just used to sign in with. 
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1 1 EcoSpace retrieval strategies 


The EcoSpaceManager component has been used quite extensively throughout this document. This component is 
responsible for providing an EcoSpace of the requested type, but so far no mention has been made regarding where this 
instance comes from. It would be reasonable to assume that the EcoSpaceManager merely creates a new instance for each 
page request. This is in fact accurate when describing the default behavior, but it is possible to modify this default behavior 
in order to fine tune your requirements between speed and memory usage. 


The following image is a subset of the one presented in the section Logical flow (a see page 10) near the beginning of this 
article. 


EcoSpace 
property not 
null? 



As you can see there is an entity entitled "EcoSpacePool". This allows the EcoSpaceManager to retrieve an existing 
EcoSpace instance from a pool, and also to return it when the page has finished with it. Retrieving an EcoSpace from a pool 
improves performance because the most commonly used object instances are likely to have already been loaded into the 
cache, avoiding a trip to the data storage altogether. 
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11.1 Pooling EcoSpaces 

The settings for pooling are defined in the Web.config file 
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<appSettings> 

Odd key = "Eco . Web . MaxPool " value = "0" /> 
<add key = "Eco . Web . MaxAge " value = "600" /> 
<! — Non relevant settings omitted — > 

</ appSettings> 


Eco.Web.MaxPool specifies how many instances may be present in the pooi. The defauit vaiue of zero indicates EcoSpace 
pooling shouid not be used. Changing this vaiue to anything greater than zero wiii enabie pooling. 


Eco.Web.MaxAge specifies the maximum age of an EcoSpace in the pooi. The purpose of the pooi is to provide a pooi of 
EcoSpace instances with commoniy accessed data in them. An EcoSpace wili be retrieved from the pooi, used, and returned 
many times during its lifetime. It Is therefore probable that during its lifetime it aiso ioads object instances which wili not be 
used very often, or even used at ail. In order to prevent the EcoSpaces' caches from becoming "bioated" this setting ailows 
you to determine the maximum age of an EcoSpace in the pooi. Once an EcoSpace is oider than the specified amount of 
time it wili be discarded and no ionger be availabie within the pooi. 


Here is an outline of the pooiing process: 


Retrieve from pool 

1 . Is there an EcoSpace in pooi? 

• No: Return a new instance. 

• Yes: Is the age of the EcoSpace less than the MaxAge? 

• Yes: Return it. 

• No: Dispose of it, and repeat step 1 

2. Invaiidate any parts of the cache that other users have made changes to (muiti-user synchronization wiil be covered in a 
iater document). 

Return to pool 

1 . Is the pool full? 

• Yes: Dispose of the EcoSpace. 

• No: Is the EcoSpace too old to be returned? 

• Yes: Dispose of the EcoSpace. 

• No: Return it to the pooi. 


11 .2 Session EcoSpaces 

When returning an EcoSpace to the pooi there must be no dirty objects (objects with changes that need saving). If this 
restriction was not in piace it would be possible to retrieve an EcoSpace from the pool containing changes made by another 
user, this behavior wouid be confusing and wouid also be likely to introduce errors. 
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The EcoSpaceManager aiiows the deveioper to specify an additionai option for the retrievai / return of EcoSpace instances, 
this option is specified via its SessionStateMode property. 
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Value 

Setting 

Never 

The EcoSpaceManager will not use the user's Session when retrieving or returning an EcoSpace instance. 

IfDirty 

If there are dirty objects in the EcoSpace at the end of the page request the EcoSpace will be stored in the user's 
Session using the key given in the SessionStateKey property. 


When an EcoSpace instance is required the EcoSpaceManager will first inspect the user's Session using the 
given key, if an EcoSpace is stored within the Session under this SessionStateKey then that instance will be used. 

Always 

This option is essentially the same as IfDirty, except the EcoSpace will always be stored in the user's Session at 
the end of the page request whether it has dirty objects or not. 


This option is useful when you wish to have instances of Transient classes in your EcoSpace. A Transient class 
can never be considered "dirty" because it is never updated to the data storage. 


As it is possibie to use more than one EcoSpaceManager on a singie page request it is possibie for a page to use muitipie 
instances of EcoSpaces. Some benefits of this are 


• The abiiity to utiiize more than one type of EcoSpace and therefore different modeis. 

• To ailow updates to objects over muitipie pages without having to commit to the data storage. For example a multi-page 
wizard for creating a new customer account. 

• Using different SessionStateKey values in order to logically separate sets of updates. For example you might use 
"NewCustomer" as the SessionStateKey for creating a new customer over multiple pages, and use "ShoppingCart" is the 
SessionStateKey for an EcoSpace which holds a single unsaved purchase order which the user is constantly modifying 
throughout their visit to the website. 
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12 Shopping cart 


The "Shopping cart" example will be demonstrated next. Some modifications will be made to the model to allow an Author to 
purchase the right to view other authors' articles. The order will remain in an unsaved state across multiple page requests by 
storing it in the user's Session state. Finally, if the user chooses to, the order will be saved to the data storage and they will 
be given access to the articles they have (fictitiously) purchased. The example will not go as far as implementing all of the 
requirements such as only giving access to purchased articles etc as that would distract from the true purpose of this 
example, which is to demonstrate how to perform the following tasks 


1 . Modify an object across multiple page requests. 

2. Perform these changes in isolation, so that the user may switch to another task part way through and then continue 
without any adverse affects. 


12.1 Preliminary changes 

Before implementing the cart there are a number of changes to be made to the existing features of the site. 


Giving articles a price 

1 . Select the Article class in the modeler. 

2. Add a new UML attribute 

• Name = Price 

• Type = decimal 

• Initial value = 0 

• Default DB value = 0 

3. Add a constraint to the Article class 

• Name = Price must be at least 1 if not free 

• Expression = (price = 0) or (price >= 1) 

4. Save changes 

5. Generate source code 

6. Rebuild the project 

7. Evolve the DB if not using the XML persistence component. 

Next the EditArticle form will be updated to allow for the input of a price. 

7. View the markup for EditArticle. aspx 

8. Beneath the markup for ArticleType add the following 


<tr> 

<th>Price</th> 

<td> 

<asp:TextBox ID="PriceTextBox" runat="server" Columns="8" MaxLength=" 8 " 
Text='<%# Bind ( "Price" ) %> ' ></asp : TextBox> 
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</td> 

</tr> 


9. Run the application and enter some prices for the articles. 


12.2 Adding orders to the model 

Next some classes will be added to the model to allow the website to record order information. 

1 . Add a new Class Diagram to the model and name it "Shopping cart" 

2. Drag the Article class from the treeview in the Modir-tab onto the new diagram 

3. Add two new classes and name them "Order" and "OrderLine" respectively. 

4. Draw a class association line from Order to OrderLine 

• 

5. Draw a class association line from Article to OrderLine 

• Adjust the multiplicities and compositions according to the diagram below 

6. Add a new attribute to the OrderLine class 

• Name = Price 

• Type = decimal 

7. Add a new attribute to the Order class 

• Name = TotalValue 

• Type = decimal 

• Attribute type = Derived (read only) 

• Derivation OCL = self.OrderLines.Price->sum 

8. Save changes to the model 

9. Generate code 

10. Rebuild the solution 

1 1 . If you are not using XML persistence click the "Evolve DB" button on the persistence mapper provider 



Order 

[.TcalPrice Depmal) 


0 ..* 

« . ^ 
1 OrderLine 


Price Decmal 

L": 
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Next some additions will be made to the model source code to make the process easier. 
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1 . Add the following method to the Article class (in Article.es): 


public static Article GetBylD ( lEcoServiceProvider serviceProvider , int id) 

{ 

//Get the article by its ID 

string query = string . Format ( "Article . alllnstances->select ( id = {0})", id); 
lOclPsService oclPs = serviceProvider . GetEcoService<IOclPsService> () ; 
lObjectList articleElements = oclPs . Execute (query ) ; 
if (articleElements . Count > 0) 

return articleElements [ 0 ] . GetValue<Article> ( ) ; 
return null; 

} 


2. Add the following methods to the Order class (Order.es). 

private OrderLine GetLineByArticle (Article article) 

{ 

foreach (OrderLine currentOrderLine in OrderLines) 
if (currentOrderLine .Article == article) 
return currentOrderLine; 

return null; 

} 

public void AddArticle (int id) 

{ 

Article article = Article . GetBylD (AsIObject (). ServiceProvider , id); 
if (GetLineByArticle (article) == null) 

{ 

OrderLine newLine = new OrderLine (AsIObject (). ServiceProvider ) ; 
OrderLines .Add (newLine) ; 
newLine . Article = article; 
newLine . Price = article . Price; 



12.3 The shopping cart control 

A control will now be created to show the articles currently in the user’s shopping cart. This control will then be added to the 
master page so that it appears on every page. 

1 . Create a new folder named "Controls" 

2. Right click the new folder and on the context menu select "Add" and then "New item" 

3. Select Web User Control and click OK 

4. Give the control the name ShoppingCart.ascx 

Next the required ECO components will be added, and the web controls required to display the contents of the cart. 


5. Add an EcoSpaceManager to the control 

• Set its EcoSpaceTypeName 

• SessionStateKey = ShoppingCart 

• SessionStateMode = Always 

• UsePool = False 
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6. Add an EcoDataSource to the control 

• ID = CartItemsDataSource 

• EcoSpaceManagerlD = EcoSpaceManagerl 

• Expression = Order.allLoadedObjects->first.OrderLines 

Note: Instead of "alllnstances" the OCL command "allLoadedObjects" is used. This will return a list of objects that have 
already been loaded into the EcoSpace's cache. As the EcoSpace being used will be private to the user and stored in their 
session it will contain exactly zero or one Order instances. 

Now some web controls will be added to show the contents of the cart. 

7. Add a Label control to the control and name it CartTotal Label 

8. Add a GridView control to the control 

• ID = CartItemsGridView 

• DataSourcelD = CartItemsDataSource 

• Remove all columns except for Article and Price 

9. Edit the columns property on CartItemsDataSource 

10. Add a new column 

• Name = Article 

• Expression = seIf.Article. Summary 

Note: The above steps will override the "Article" column which is added by default. Instead of a column with the expression 
"self. Article. asString" the column will show Article. Summary, which is the title of the article combined with the name of the 
author. 


EcoSpaceManager - EcoSpaceManagerl 
EcoDataSource - CartItemsDataSource 


Article Price 


abc_123 0.3 
abc_123 0.3 
abc_123 0.3 
abc_123 0.3 
abc 123 0.3 


1 2. To make life a little easier later add the following static method to the control’s source. This will give easy access to the 
current Order instance. 


public static Order GetCartO 
{ 

//Create an EcoSpaceStrategyHandler to manage the EcoSpace for us 
//The settings will ensure it is retrieved from the Session if present 
//otherwise a new instance will be created 
EcoSpaceStrategyHandler ecoSpaceProvider = 

new EcoSpaceStrategyHandler (EcoSpaceStrategyHandler . SessionStateMode . Always , 
typeof (QuickStartEcoSpace) , " ShoppingCart " , false); 

//Get an instance of the EcoSpace 

QuickStartEcoSpace ecoSpace = (QuickStartEcoSpace) ecoSpaceProvider . GetEcoSpace () ; 
//Get the only loaded Order in the EcoSpace 
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lOclService oclService = ecoSpace . GetEcoService<IOclService> ( ) ; 
Order result = 

oclService . Evaluate ( "Order . allLoadedOb jects->f irst " ) . GetValue<Order> ( ) ; 

//Create a new order if none was found 
if (result == null) 

result = new Order (ecoSpace) ; 

//Return the EcoSpace to the session 
ecoSpaceProvider . ReturnEcoSpace (ecoSpace) ; 
return result; 

} 


Note: The EcoSpaceStrategyHandler is the class used internally by the EcoSpaceManager component. It Is important to use 
this class when storing EcoSpace Instances In the session as it stores the EcoSpace in a way that makes it possible to use 
SQL Server session state when web farming. 


Next the control will be added to the master page. 


1 3. View the markup for the master page. 

14. Change the markup like so 


<table> 

<tr> 

<tdx/td> 

<td> 

<asp:ContentPlaceHolder ID="ContentPlaceHolder 1 " runat=" server " > 
</ asp : ContentPlaceHolder> 

</td> 

</tr> 

</table> 


Note: If we use tables for layout we will apparently go to hell, therefore I recommend you research CSS layouts. 


1 5. In design mode drag the ShoppingCart control and drop It into the empty table cell 


Order.cs Sitel.Master start Page | 

Kl 

Welcome to mv ECO driven website 

♦ 

• Error message 1. 

• Error message 2. 

EcoSpaceManager - EcoSpaceManagerl j 
EcoDataSource * CartItemsDataSource 


Article Price 


abc 123 0.3 
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abc_123 0.3 
abc_123 0.3 
abc_123 0.3 
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12.4 Show all available articles 


Next a web form will be created to show all articles. A link will be added to enable the user to add the article to their shopping 
cart. 


1 . Edit Default.aspx and add a hyperlink to /AIIArticles.aspx 

2. Create a new Web Content Form in the root of the site 

3. Name it AIIArticles.aspx 

4. Add an EcoSpaceManager and set its EcoSpaceTypeName 

5. Add an EcoDataSource 

• ID = Article DataSou roe 

• EcoSpaceManagerlD = EcoSpaceManagerl 

• Expression = Article. alllnstances 

6. Add a DataList control to the form 

• ID = ArticlesDataList 

• DataSourcelD = Article DataSou roe 

• Set its markup as follows 


<asp : DataList ID="ArticlesDataList " runat="server"> 

<HeaderTemplate> 

<table> 

<thead> 

<tr> 

<th>Article</th> 

<th>Price</th> 

</tr> 

</thead> 

<tbody> 

</HeaderTemplate> 

<ItemTemplate> 

<tr> 

<td><%# Eval ( "Summary" ) %></td> 

<td><%# Eval ( "Price" , "{0:c}") %></td> 

</tr> 

<tr> 

<th colspan=" 2 " >Descript ion</th> 

</tr> 

<tr> 

<td colspan=" 2 " ><%# Eval ( "Description" ) %></td> 

</tr> 

<tr> 

<td colspan="2"> 

<asp : LinkButton ID="AddToCartLinkButton" runat="server" 
CommandName="AddToCart " Text="Add to cart" /> 

</td> 

</tr> 

</ItemTemplate> 

<F oot e r Tempi at e> 

</tbody> 

</table> 

</ Foot e r Tempi at e> 

</asp:DataList> 
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Note: This markup Is a simple repeating pattern with data binding to various properties on Article. A LInkButton has been 
added to Invoke a method to add the Article to the current Order. 


ContentPlaceHolderl (Custom) I 

EcoSpaceManager * EcoSpaceManageri 


EcoDataSource - ArtideDataSource 

Aiticle Piice 

abc_123 £1.10 
Desciipfion 
abc_123 
Add to cart 
abc_123 £1.10 
Desciipfion 
abc_123 
Add to cart 
abc_123 £1.10 
Desciipfion 
abc_123 
Add to cart 
abc_123 £1.10 
Desciipfion 


7. In the code-behind call DataBlnd() in the Page_Load method. 

8. To bind the ID of the article to the LInkButton add the following code to the ItemDataBound event. 


protected void ArticlesDataList_ItemDataBound (object sender, DataListItemEventArgs e) 

{ 

LInkButton addToCartLinkButton = 

(LinkButton) e . Item .FindControl ( "AddToCartLinkButton" ) ; 
if (addToCartLinkButton != null) 

addToCartLinkButton . CommandArgument = DataBinder . Eval (e . Item . Dataltem, 

"ID") .ToStringO ; 

} 


9. When the user clicks the "Add to cart" link button the article should be added to the cart. To achieve this add the following 
Implementation to the ItemCommand event 


protected void ArticlesDataList_ItemCommand (object source, DataListCommandEventArgs e) 

{ 

switch (e . CommandName) 

{ 

case "AddToCart": 

int articlelD = int . Parse ( (string) e . CommandArgument , 

NumberEormatInf o . Invariantinfo) ; 

ShoppingCart . GetCart ( ) . AddArticle (articlelD) ; 

DataBind ( ) ; 

break ; 

default : 

throw new NotImplementedException ( "Unknown command: " + e . CommandName) ; 

} //switch 

J 

Now run the application, select All Articles and click "Add to cart" next to one or more articles. 
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AA elcoiiie to mv ECO driven website 


I Article 

Price 

•Ailicle 

Piice 

My second article by Mr John Smith 

2.5 

My second article by Mr John Smith £2.50 

My first article by Mr John Smifii 

2.5 

Description 


Mr first article by Mr Fred Smith 

0 

My article is written in Latin. 



Add to cart 

My first article by Mr John Smith £2.50 


Description 
My article is written in Latin. 

Add to cart 

Mr first article by Mr Fred Smith £0.00 
Description 
This IS my article, in Latin. 

Add to cart 

My second article by Mr Fred Smith £0.00 
Description 
This is my article, in Latin. 

Add to cart 
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13 Summary 


This document has demonstrated how to use ECO in an ASP .NET web appiication. It has demonstrated how to bind an 
ECO data source to standard web Ul controis and expiained how EcoSpace iifetime management works. It was not intended 
to be a comprehensive exampie of how to impiement a fuiiy commeroiai shopping cart to a website. Instead it is a 
demonstration of how to modify objects over muitipie page requests, and to isoiate these operations into separate iogicai 
groups so that they do not interfere with each other. 


This technique can be used at various piaces within a iarge website by using different vaiues for the SessionStateKey 
property on the EcoSpaceManager (or when oreating an EcoSpaceStrategyHandier retrieve the EcoSpace instance in 
code). Aithough in this exampie the SessionStateMode was set to Aiways you may decide it is more appropriate to set this 
property to ifDirty and aiiow the EcoSpace to cooperate in the pooi when there are no unsaved changes. 


This document has not covered the use of the ECO web providers (membership, roies etc) as its purpose was to buiid an 
applioation that has a business modei whioh may be used in both a web and WinForm applioation. Use of these providers 
may be covered in a iater document. 
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